Skip to main content

Optimizing Bone Entities Count

By default, every animated skeleton bone has a corresponding entity in the ECS world. These entity positions get updated with computed animations by Rukhanka, and the hierarchy is processed by entity transformation systems. With a high bone count, updating these entities will take a significant amount of processing time. Often these bone entities are not needed, at least not all of them. It is advisable to keep only bones that are required for gameplay (bones with attachments, for example). Rukhanka provides functionality to strip unneeded bone entities.

Unfortunately, Unity's builtin bone stripping functionality of the model importer window cannot be used: Unity Model Importer Bone Stripping

Rukhanka reads full hierarchy information from Unity avatar during the baking phase, so Optimize Game Objects checkbox should be unchecked.

To remove unneeded entities from the ECS world there are several options available:

BakingOnlyEntityAuthoring script​

Use the BakingOnlyEntityAuthoring component provided by the Entities package. By adding this component, the entity corresponding to this GameObject and all of its children will be stripped from the ECS world. Unfortunately, there is no option to configure its behavior for keeping some of its children (often attachments are bound to the bone deeper in the hierarchy). This approach is very good for situations when the model does not have attachments at all. Adding the BakingOnlyEntityAuthoring component to the rig root bone will strip the entire bone entities hierarchy.

Baking Only Entity Authoring

Automatic unreferenced bone entity removal​

Rukhanka provides an option for automatic bone entity removal of all unreferenced bones. I.e. if no component requires this particular bone entity (for example, physics collider, IK entity, attached object, etc.), then this bone entity will be removed from the world. To activate this mode option Automatic should be selected from the Bone Entity Stripping Mode selector of the 'RigDefinitionAuthoring' script.

Optimization Automatic

Manual selection of removed bone entities​

If more precise stripping granularity is needed, then a special bone mask can be used. Optimization mask is just the default Unity AvatarMask object. Fill it with the specifying avatar in the Use skeleton from field and press the Import skeleton button. Enabled bones in it will stay as entities and disabled ones will be stripped:

Optimization AvatarMask

Then set the configured avatar mask in the RigDefinitionAuthoring Bone Stripping Mask field with Bone Entity Stripping Mode set to Manual:

Rig Definition Bone Strip Mask

Important

By using a bone stripping mask whole entity bone hierarchy will be flattened (i.e. Parent component will be removed from bone entities). Unparented bones must have a valid animation track (just one identity keyframe will suffice) associated with it to be animated correctly. Otherwise, the bone will be driven by LocalTransform component values, which is a world pose if the parent is not present.